DateAndTime.DateDiff Method

Definition

Возвращает значение, указывающее количество интервалов времени между двумя значениями Date.Returns a value specifying the number of time intervals between two Date values.

Overloads

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

Возвращает значение типа long, указывающее количество интервалов времени между двумя значениями Date.Returns a long value specifying the number of time intervals between two Date values.

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

Возвращает значение типа long, указывающее количество интервалов времени между двумя значениями Date.Returns a long value specifying the number of time intervals between two Date values.

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

Возвращает значение типа long, указывающее количество интервалов времени между двумя значениями Date.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. Значение перечисления DateInterval или строковое выражение, представляющее интервал времени, используемый в качестве единицы измерения разницы между Date1 и Date2.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. Значение, выбранное из перечисления FirstDayOfWeek, указывающее первый день недели.A value chosen from the FirstDayOfWeek enumeration that specifies the first day of the week. Если этот параметр не задан, используется значение Sunday.If not specified, Sunday is used.

WeekOfYear
FirstWeekOfYear

Необязательный параметр.Optional. Значение, выбранное из перечисления FirstWeekOfYear, указывающее первую неделю года.A value chosen from the FirstWeekOfYear enumeration that specifies the first week of the year. Если этот параметр не задан, используется значение Jan1.If not specified, Jan1 is used.

Returns

Int64

Значение типа long, указывающее количество интервалов времени между двумя значениями Date.A long value specifying the number of time intervals between two Date values.

Exceptions

Значение Date1, Date2 или DayofWeek выходит за пределы допустимого диапазона.Date1, Date2, or DayofWeek is out of range.

Значение Date1 или Date2 имеет недопустимый тип.Date1 or Date2 is of an invalid type.

Examples

В этом примере функция DateDiff используется для вывода количества дней между заданной и текущей датами.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

Можно использовать функцию DateDiff, чтобы определить, сколько заданных интервалов времени существует между двумя значениями даты и времени.You can use the DateDiff function to determine how many specified time intervals exist between two date/time values. Например, можно использовать DateDiff, чтобы вычислить количество дней между двумя датами или число недель между сегодняшней и концом года.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 вычитает значение Date1 из значения Date2, чтобы получить разницу.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. Поскольку Date1 и Date2 относятся к Date типу данных, они содержат точные значения даты и времени в 100-наносекундных тактах в системном таймере.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. Однако DateDiff всегда возвращает количество интервалов времени в виде значения Long.However, DateDiff always returns the number of time intervals as a Long value.

    Если Date1 представляет более позднюю дату и время, чем Date2, DateDiff возвращает отрицательное число.If Date1 represents a later date and time than Date2, DateDiff returns a negative number.

  • Интервалы дня.Day Intervals. Если Interval имеет значение DateInterval.DayOfYear, то оно обрабатывается так же, как DateInterval.Day, так как DayOfYear не является значимой единицей времени для временного интервала.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. Если Interval имеет значение DateInterval.WeekOfYear, то возвращаемое значение представляет число недель между первым днем недели, содержащей Date1, и первым днем недели, содержащей Date2.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. В следующем примере показано, как это дает результаты, отличающиеся от DateInterval.Weekday.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)
    

    В предыдущем примере DateDiff возвращает значение 0 для wD, так как разница между двумя датами меньше семи дней, но возвращает 1 в wY, так как существует разница в семь дней между первыми днями соответствующих календарных недель.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. Если Interval имеет значение DateInterval.Year, то возвращаемое значение вычисляется исключительно из частей года Date1 и Date2.If Interval is set to DateInterval.Year, the return value is calculated purely from the year parts of Date1 and Date2. Аналогичным образом возвращаемое значение для DateInterval.Month вычисляется исключительно из частей года и месяца аргументов, а для DateInterval.Quarter из кварталов, содержащих две даты.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.

    Например, при сравнении 31 декабря с 1 января в следующем году DateDiff возвращает 1 для DateInterval.Year, DateInterval.Quarterили DateInterval.Month, хотя истечет только один день.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.

    Для языков и региональных параметров, таких как японский, с несколькими Эр, метод DateDiff не возвращает разницы в годах, если разница охватывает две или более Эр.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. Вместо этого можно вычислить разницу в значениях, возвращаемых свойством Year, как показано в следующем примере: date2.Year - date1.Year.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. Поскольку все значения Date поддерживаются структурой DateTime, ее методы предоставляют дополнительные возможности для поиска интервалов времени.Since every Date value is supported by a DateTime structure, its methods give you additional options in finding time intervals. Например, можно использовать метод Subtract в любой из его перегруженных форм: DateTime.Subtract вычитает TimeSpan из переменной Date, чтобы вернуть другое Date значение, а DateTime.Subtract вычитает значение Date для возврата TimeSpan.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
    

Аргумент Interval может иметь одно из следующих значений.The Interval argument can have one of the following settings.

Значение перечисленияEnumeration value Строковое значениеString value Единица разницы во времениUnit of time difference
DateInterval.Day "d""d" ДеньDay
DateInterval.DayOfYear "y""y" ДеньDay
DateInterval.Hour "h""h" ЧасHour
DateInterval.Minute \n"n" МинутаMinute
DateInterval.Month "m""m" МесяцMonth
DateInterval.Quarter формате"q" КварталQuarter
DateInterval.Second "s""s" СекундаSecond
DateInterval.Weekday "w""w" НеделяWeek
DateInterval.WeekOfYear НН"ww" Календарная неделяCalendar week
DateInterval.Year "yyyy""yyyy" ГодYear

Аргумент DayOfWeek может иметь одно из следующих значений.The DayOfWeek argument can have one of the following settings.

Значение перечисленияEnumeration value ЗначениеValue DescriptionDescription
FirstDayOfWeek.System 00 Первый день недели, указанный в параметрах системыFirst day of week specified in system settings
FirstDayOfWeek.Sunday 11 Воскресенье (по умолчанию)Sunday (default)
FirstDayOfWeek.Monday 22 Понедельник (соответствует стандарту ISO 8601, раздел 3,17)Monday (complies with ISO standard 8601, section 3.17)
FirstDayOfWeek.Tuesday 33 ВторникTuesday
FirstDayOfWeek.Wednesday 44 СредаWednesday
FirstDayOfWeek.Thursday 55 ЧетвергThursday
FirstDayOfWeek.Friday 66 ПятницаFriday
FirstDayOfWeek.Saturday 77 СубботаSaturday

Аргумент WeekOfYear может иметь одно из следующих значений.The WeekOfYear argument can have one of the following settings.

Значение перечисленияEnumeration value ЗначениеValue DescriptionDescription
FirstWeekOfYear.System 00 Первая неделя года, указанная в параметрах системыFirst week of year specified in system settings
FirstWeekOfYear.Jan1 11 Неделя, в которой происходит 1 января (по умолчанию)Week in which January 1 occurs (default)
FirstWeekOfYear.FirstFourDays 22 Неделя, в которой в новом году по крайней мере четыре дня (соответствует стандарту ISO 8601, раздел 3,17)Week that has at least four days in the new year (complies with ISO standard 8601, section 3.17)
FirstWeekOfYear.FirstFullWeek 33 Первая полная неделя в новом годуFirst full week in the new year

See also

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

Возвращает значение типа long, указывающее количество интервалов времени между двумя значениями Date.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);
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. Значение перечисления DateInterval или строковое выражение, представляющее интервал времени, используемый в качестве единицы измерения разницы между Date1 и Date2.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. Значение, выбранное из перечисления FirstDayOfWeek, указывающее первый день недели.A value chosen from the FirstDayOfWeek enumeration that specifies the first day of the week. Если этот параметр не задан, используется значение Sunday.If not specified, Sunday is used.

WeekOfYear
FirstWeekOfYear

Необязательный параметр.Optional. Значение, выбранное из перечисления FirstWeekOfYear, указывающее первую неделю года.A value chosen from the FirstWeekOfYear enumeration that specifies the first week of the year. Если этот параметр не задан, используется значение Jan1.If not specified, Jan1 is used.

Returns

Int64

Значение типа long, указывающее количество интервалов времени между двумя значениями Date.A long value specifying the number of time intervals between two Date values.

Exceptions

Значение Date1, Date2 или DayofWeek выходит за пределы допустимого диапазона.Date1, Date2, or DayofWeek is out of range.

Значение Date1 или Date2 имеет недопустимый тип.Date1 or Date2 is of an invalid type.

Examples

В этом примере функция DateDiff используется для вывода количества дней между заданной и текущей датами.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

Можно использовать функцию DateDiff, чтобы определить, сколько заданных интервалов времени существует между двумя значениями даты и времени.You can use the DateDiff function to determine how many specified time intervals exist between two date/time values. Например, можно использовать DateDiff, чтобы вычислить количество дней между двумя датами или число недель между сегодняшней и концом года.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 вычитает значение Date1 из значения Date2, чтобы получить разницу.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. Поскольку Date1 и Date2 относятся к Date типу данных, они содержат точные значения даты и времени в 100-наносекундных тактах в системном таймере.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. Однако DateDiff всегда возвращает количество интервалов времени в виде значения Long.However, DateDiff always returns the number of time intervals as a Long value.

    Если Date1 представляет более позднюю дату и время, чем Date2, DateDiff возвращает отрицательное число.If Date1 represents a later date and time than Date2, DateDiff returns a negative number.

  • Интервалы дня.Day Intervals. Если Interval имеет значение DateInterval.DayOfYear, то оно обрабатывается так же, как DateInterval.Day, так как DayOfYear не является значимой единицей времени для временного интервала.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. Если Interval имеет значение DateInterval.WeekOfYear, то возвращаемое значение представляет число недель между первым днем недели, содержащей Date1, и первым днем недели, содержащей Date2.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. В следующем примере показано, как это дает результаты, отличающиеся от DateInterval.Weekday.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)
    

    В предыдущем примере DateDiff возвращает значение 0 для wD, так как разница между двумя датами меньше семи дней, но возвращает 1 в wY, так как существует разница в семь дней между первыми днями соответствующих календарных недель.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. Если Interval имеет значение DateInterval.Year, то возвращаемое значение вычисляется исключительно из частей года Date1 и Date2.If Interval is set to DateInterval.Year, the return value is calculated purely from the year parts of Date1 and Date2. Аналогичным образом возвращаемое значение для DateInterval.Month вычисляется исключительно из частей года и месяца аргументов, а для DateInterval.Quarter из кварталов, содержащих две даты.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.

    Например, при сравнении 31 декабря с 1 января в следующем году DateDiff возвращает 1 для DateInterval.Year, DateInterval.Quarterили DateInterval.Month, хотя истечет только один день.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.

    Для языков и региональных параметров, таких как японский, с несколькими Эр, метод DateDiff не возвращает разницы в годах, если разница охватывает две или более Эр.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. Вместо этого можно вычислить разницу в значениях, возвращаемых свойством Year, как показано в следующем примере: date2.Year - date1.Year.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. Поскольку все значения Date поддерживаются структурой DateTime, ее методы предоставляют дополнительные возможности для поиска интервалов времени.Since every Date value is supported by a DateTime structure, its methods give you additional options in finding time intervals. Например, можно использовать метод Subtract в любой из его перегруженных форм: DateTime.Subtract вычитает TimeSpan из переменной Date, чтобы вернуть другое Date значение, а DateTime.Subtract вычитает значение Date для возврата TimeSpan.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
    

Аргумент Interval может иметь одно из следующих значений.The Interval argument can have one of the following settings.

Значение перечисленияEnumeration value Строковое значениеString value Единица разницы во времениUnit of time difference
DateInterval.Day "d""d" ДеньDay
DateInterval.DayOfYear "y""y" ДеньDay
DateInterval.Hour "h""h" ЧасHour
DateInterval.Minute \n"n" МинутаMinute
DateInterval.Month "m""m" МесяцMonth
DateInterval.Quarter формате"q" КварталQuarter
DateInterval.Second "s""s" СекундаSecond
DateInterval.Weekday "w""w" НеделяWeek
DateInterval.WeekOfYear НН"ww" Календарная неделяCalendar week
DateInterval.Year "yyyy""yyyy" ГодYear

Аргумент DayOfWeek может иметь одно из следующих значений.The DayOfWeek argument can have one of the following settings.

Значение перечисленияEnumeration value ЗначениеValue DescriptionDescription
FirstDayOfWeek.System 00 Первый день недели, указанный в параметрах системыFirst day of week specified in system settings
FirstDayOfWeek.Sunday 11 Воскресенье (по умолчанию)Sunday (default)
FirstDayOfWeek.Monday 22 Понедельник (соответствует стандарту ISO 8601, раздел 3,17)Monday (complies with ISO standard 8601, section 3.17)
FirstDayOfWeek.Tuesday 33 ВторникTuesday
FirstDayOfWeek.Wednesday 44 СредаWednesday
FirstDayOfWeek.Thursday 55 ЧетвергThursday
FirstDayOfWeek.Friday 66 ПятницаFriday
FirstDayOfWeek.Saturday 77 СубботаSaturday

Аргумент WeekOfYear может иметь одно из следующих значений.The WeekOfYear argument can have one of the following settings.

Значение перечисленияEnumeration value ЗначениеValue DescriptionDescription
FirstWeekOfYear.System 00 Первая неделя года, указанная в параметрах системыFirst week of year specified in system settings
FirstWeekOfYear.Jan1 11 Неделя, в которой происходит 1 января (по умолчанию)Week in which January 1 occurs (default)
FirstWeekOfYear.FirstFourDays 22 Неделя, в которой в новом году по крайней мере четыре дня (соответствует стандарту ISO 8601, раздел 3,17)Week that has at least four days in the new year (complies with ISO standard 8601, section 3.17)
FirstWeekOfYear.FirstFullWeek 33 Первая полная неделя в новом годуFirst full week in the new year

See also

Applies to