DateDiff-Funktion (Visual Basic)

Artikel
08/20/2008

Aktualisiert: November 2007

Gibt einen Wert vom Typ Long zurück, der die Anzahl der Zeitintervalle zwischen zwei Date-Werten angibt.

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

Parameter

Interval
Erforderlich. Wert aus der DateInterval-Enumeration oder String-Ausdruck, der das Zeitintervall angibt, das Sie als Einheit für die Differenz zwischen Date1 und Date2 verwenden möchten.
Date1
Erforderlich. Date. Der erste Datums-/Uhrzeitwert, den Sie in der Berechnung verwenden möchten.
Date2
Erforderlich. Date. Der zweite Datums-/Uhrzeitwert, den Sie in der Berechnung verwenden möchten.
DayOfWeek
Optional. Ein Wert aus der FirstDayOfWeek-Enumeration, der den ersten Tag der Woche angibt. Wird kein bestimmter Wert angegeben, wird FirstDayOfWeek.Sunday verwendet.
WeekOfYear
Optional. Ein Wert aus der FirstWeekOfYear-Enumeration, der die erste Woche des Jahres angibt. Wird kein bestimmter Wert angegeben, wird FirstWeekOfYear.Jan1 verwendet.

Einstellungen

Das Interval-Argument kann eine der folgenden Einstellungen haben.

Enumerationswert	Zeichenfolgenwert	Einheit der Zeitdifferenz
DateInterval.Day	"d"	Tag
DateInterval.DayOfYear	"y"	Tag
DateInterval.Hour	"h"	Stunde
DateInterval.Minute	"n"	Minute
DateInterval.Month	"m"	Monat
DateInterval.Quarter	"q"	Quartal
DateInterval.Second	"s"	Sekunde
DateInterval.Weekday	"w"	Woche
DateInterval.WeekOfYear	"ww"	Kalenderwoche
DateInterval.Year	"yyyy"	Jahr

Das DayOfWeek-Argument kann eine der folgenden Einstellungen haben:

Enumerationswert	Wert	Beschreibung
FirstDayOfWeek.System	0	Erster Tag der Woche laut Systemeinstellungen
FirstDayOfWeek.Sunday	1	Sonntag (Standardwert)
FirstDayOfWeek.Monday	2	Montag (entspricht ISO-Norm 8601, Abschnitt 3.17)
FirstDayOfWeek.Tuesday	3	Dienstag
FirstDayOfWeek.Wednesday	4	Mittwoch
FirstDayOfWeek.Thursday	5	Donnerstag
FirstDayOfWeek.Friday	6	Freitag
FirstDayOfWeek.Saturday	7	Samstag

Das WeekOfYear-Argument kann eine der folgenden Einstellungen haben.

Enumerationswert	Wert	Beschreibung
FirstWeekOfYear.System	0	Erste Woche des Jahres laut Systemeinstellungen
FirstWeekOfYear.Jan1	1	Die Woche, in der der 1. Januar liegt (Standardwert)
FirstWeekOfYear.FirstFourDays	2	Die erste Woche im neuen Jahr, die mindestens vier Tage hat (entspricht ISO-Norm 8601, Abschnitt 3.17)
FirstWeekOfYear.FirstFullWeek	3	Die erste vollständige Woche im neuen Jahr

Ausnahmen

Ausnahmetyp	Fehlernummer	Bedingung
ArgumentException	5	Ungültiges Interval.
ArgumentException	5	Date1, Date2 oder DayofWeek liegt außerhalb des Bereichs.
InvalidCastException	13	Date1 oder Date2 hat einen ungültigen Typ.

Beachten Sie die Spalte "Fehlernummer", wenn Sie Visual Basic 6.0-Anwendungen aktualisieren, die eine unstrukturierte Fehlerbehandlung verwenden. (Sie können die Fehlernummer mit der Number-Eigenschaft (Err-Objekt) vergleichen.) Wenn möglich, sollten Sie jedoch erwägen, eine solche Fehlersteuerung durch eine Übersicht über die strukturierte Ausnahmebehandlung für Visual Basic zu ersetzen.

Hinweise

Mit der DateDiff-Funktion können Sie ermitteln, wie viele angegebene Zeitintervalle zwischen zwei Zeitpunkten liegen. Sie können mit DateDiff beispielsweise die Anzahl der Tage zwischen zwei Datumsangaben oder die Anzahl der Wochen zwischen dem heutigen Tag und dem Ende des Jahres berechnen.

Verhalten

**Behandlung von Parametern.**DateDiff subtrahiert den Wert von Date1 vom Wert von Date2, um die Differenz zu erzeugen. Keiner der Werte wird im aufrufenden Programm geändert.
Rückgabewerte. Da Date1 und Date2 zum Date-Datentyp gehören, enthalten sie Datums- und Zeitwerte mit einer Genauigkeit von 100 Nanosekunden im Systemzeitgeber. DateDiff gibt jedoch die Anzahl der Zeitintervalle stets als Long-Wert zurück.

Wenn Date1 einen Zeitpunkt angibt, der nach Date2 liegt, gibt DateDiff eine negative Zahl zurück.
Tagesintervalle. Wenn Interval auf DateInterval.DayOfYear festgelegt wird, wird es ebenso behandelt wie DateInterval.Day, da DayOfYear keine sinnvolle Einheit für ein Zeitintervall ist.

Wochenintervalle. Wenn Interval auf DateInterval.WeekOfYear festgelegt wird, gibt der Rückgabewert die Anzahl der Wochen zwischen dem ersten Tag der Woche an, der Date1 enthält, und dem ersten Tag der Woche, der Date2 enthält. Das folgende Beispiel veranschaulicht, dass hierdurch mit DateInterval.Weekday verschiedene Ergebnisse berechnet werden.

' 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)

Im obigen Beispiel gibt DateDiff den Wert 0 (null) für wD zurück, da die Differenz zwischen den beiden Datumsangaben weniger als sieben Tage beträgt. Für wY wird jedoch 1 zurückgegeben, da zwischen dem jeweils ersten Tag der betreffenden Kalenderwochen eine Differenz von sieben Tagen besteht.

Vorsicht:
Wenn die Zeitkomponente von Date1 größer ist als die von Date2 und Interval auf DateInterval.WeekOfYear festgelegt ist, gibt die DateDiff-Funktion einen Wert zurück, der dem richtigen Wert minus eins entspricht.

Größere Intervalle. Wenn Interval auf DateInterval.Year festgelegt wird, wird der Rückgabewert nur anhand der Jahreswerte in Date1 und Date2 berechnet. Dementsprechend wird der Rückgabewert für DateInterval.Month nur anhand der Jahres- und Monatswerte der Argumente berechnet und für DateInterval.Quarter anhand der Quartale, welche die beiden Datumsangaben enthalten.

Wenn z. B. der 31. Dezember mit dem 1. Januar des unmittelbar darauf folgenden Jahres verglichen wird, gibt DateDiff für DateInterval.Year, DateInterval.Quarter und DateInterval.Month den Wert 1 zurück, obwohl nur ein Tag vergangen ist.
Weitere Intervalle. Da jeder Date-Wert von einer DateTime-Struktur unterstützt wird, geben deren Methoden Ihnen zusätzliche Möglichkeiten für die Ermittlung von Zeitintervallen. Sie können die Subtract-Methode z. B. in einer ihrer überladenen Formen verwenden: DateTime.Subtract subtrahiert einen TimeSpan-Wert von einer Date-Variablen und gibt einen anderen Date-Wert zurück, und DateTime.Subtract subtrahiert einen Date-Wert und gibt einen TimeSpan-Wert zurück. Sie können die Dauer eines Prozesses (in Millisekunden) bestimmen. Beachten Sie dazu das folgende Beispiel.
```
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
```

Beispiel

In diesem Beispiel wird die DateDiff-Funktion verwendet, um die Anzahl der Tage zwischen einem angegebenen und dem heutigen Datum zu ermitteln.

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)