Функция DateDiff (Visual Basic)

Статья
11/05/2008

Обновлен: Ноябрь 2007

Возвращает значение типа Long, указывающее количество интервалов времени между двумя значениями Date.

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

Параметры

Interval
Обязательный параметр. Значение перечисления DateInterval или выражение String, представляющее интервал времени, используемый в качестве единицы измерения разницы между Date1 и Date2.
Date1
Обязательный параметр. Date. Первое значение даты/времени для использования в расчете.
Date2
Обязательный параметр. Date. Второе значение даты/времени для использования в расчете.
DayOfWeek
Необязательный параметр. Значение из перечисления FirstDayOfWeek, задающее первый день недели. Если параметр не задан, то используется значение FirstDayOfWeek.Sunday.
WeekOfYear
Необязательный параметр. Значение из перечисления FirstWeekOfYear, задающее первую неделю года. Если параметр не задан, то используется значение FirstWeekOfYear.Jan1.

Параметры

Аргумент Interval может принимать одно из следующих значений:

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

Аргумент DayOfWeek может принимать одно из следующих значений:

Значение перечисления	Значение	Описание
FirstDayOfWeek.System	0	Первый день недели, заданный в настройках системы
FirstDayOfWeek.Sunday	1	Воскресенье (по умолчанию)
FirstDayOfWeek.Monday	2	Понедельник (соответствует стандарту ISO 8601, раздел 3.17)
FirstDayOfWeek.Tuesday	3	Вторник
FirstDayOfWeek.Wednesday	4	Среда
FirstDayOfWeek.Thursday	5	Четверг
FirstDayOfWeek.Friday	6	Пятница
FirstDayOfWeek.Saturday	7	Суббота

Аргумент WeekOfYear может принимать одно из следующих значений:

Значение перечисления	Значение	Описание
FirstWeekOfYear.System	0	Первая неделя года, заданная в настройках системы
FirstWeekOfYear.Jan1	1	Неделя, на которую приходится 1 января (по умолчанию)
FirstWeekOfYear.FirstFourDays	2	Неделя, на которую приходится не меньше четырех дней нового года (соответствует стандарту ISO 8601, раздел 3.17)
FirstWeekOfYear.FirstFullWeek	3	Первая полная неделя в новом году

Исключения

Тип исключения	Номер ошибки	Условия
ArgumentException	5	Недопустимое значение Interval.
ArgumentException	5	Значение Date1, Date2 или DayofWeek выходит за пределы допустимого диапазона.
InvalidCastException	13	Значение Date1 или Date2 имеет недопустимый тип.

См. столбец "Номер ошибки", если выполняется обновление приложений Visual Basic версии 6.0, в которых используется неструктурированная обработка ошибок. (Номер ошибки можно сравнить со значением Свойство Number (объект Err).) Тем не менее, по возможности следует заменить эту систему работы с ошибками на Обзор структурной обработки исключений в Visual Basic.

Заметки

Для определения промежутка времени между двумя значениями даты или времени в заданных единицах измерения можно использовать функцию DateDiff. Например, с помощью функции DateDiff можно вычислить количество дней между двумя датами или число недель от текущего дня до конца года.

Поведение

Обработка параметров. Функция DateDiff вычитает значение Date1 из значения Date2, возвращая разность. В вызывающей программе не изменяется ни одно из значений.
Возвращаемые значения. Поскольку параметры Date1 и Date2 относятся к типу данных Date, они содержат значения даты и времени с точностью до 100-наносекундных квантов времени системного таймера. Тем не менее, функция DateDiff всегда возвращает количество интервалов времени в значении типа Long.

Если Date1 представляет более позднюю дату, чем Date2, то функция DateDiff возвращает отрицательное число.
Дневные интервалы. Если параметр Interval равен DateInterval.DayOfYear, то он рассматривается так же, как DateInterval.Day, поскольку DayOfYear не является значимой единицей измерения интервала времени.

Недельные интервалы. Если параметр Interval имеет значение DateInterval.WeekOfYear, то возвращаемое значение соответствует числу недель между первым днем недели, содержащей дату Date1, и первым днем недели, содержащей дату Date2. В следующем примере показано, как это дает различные результаты для 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, так как разница между двумя датами меньше семи дней, а в wY функция возвращает 1, так как разница между первыми днями соответствующих календарных недель составляет семь дней.

Внимание!
Если временная часть Date1 больше, чем у Date2, и Interval имеет значение DateInterval.WeekOfYear, то функция DateDiff возвращает значение, на 1 меньшее правильного значения.

Более крупные интервалы. Если параметр Interval равен DateInterval.Year, то возвращаемое значение вычисляется исключительно как разность годовых частей Date1 и Date2. Аналогичным образом, возвращаемое значение для DateInterval.Month вычисляется исключительно из частей года и месяца аргументов, а для DateInterval.Quarter — из значений кварталов, к которым относятся обе даты.

Например, при сравнении 31 декабря с 1 января следующего года DateDiff возвращает значение 1 для DateInterval.Year, DateInterval.Quarter или DateInterval.Month, даже если прошел только один день.
Прочие интервалы. Поскольку все значения Date поддерживаются структурой DateTime, ее методы предоставляют дополнительные возможности для определения интервалов времени. Например, можно использовать метод Subtract в любой из его перегруженных форм: DateTime.Subtract вычитает TimeSpan из переменной Date, возвращая новое значение Date, а DateTime.Subtract вычитает значение Date, возвращая TimeSpan. Можно засечь время выполнения процесса в миллисекундах, как показано в следующем примере:
```
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 Integer = runLength.Milliseconds
```

Пример

В этом примере функция DateDiff используется для вывода количества дней между заданной и текущей датами.

Dim firstDate, msg As String
Dim secondDate As Date
firstDate = InputBox("Enter a date")
secondDate = CDate(firstDate)
msg = "Days from today: " & DateDiff(DateInterval.Day, Now, secondDate)
MsgBox(msg)