DateDiff 函式 (Visual Basic)
更新：2007 年 11 月
傳回指定兩個 Date 值之間時間間隔數的 Long 值。
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
必要項。代表您希望用以做為 Date1 和 Date2 間差值單位之時間間隔的 DateInterval 列舉值或 String 運算式。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 |
一月一日當週 (預設值) |
FirstWeekOfYear.FirstFourDays |
2 |
新年度至少有四天在該週 (符合 ISO 8601 標準，第 3.17 節) |
FirstWeekOfYear.FirstFullWeek |
3 |
新年度的第一個完整星期 |
例外狀況
例外狀況類型 |
錯誤代碼 |
條件 |
|---|---|---|
Interval 無效。 |
||
Date1、Date2 或 DayofWeek 超過範圍。 |
||
Date1 或 Date2 的型別無效。 |
如果將使用非結構化錯誤處理的 Visual Basic 6.0 應用程式升級，請參閱「錯誤代碼」資料行 (您可以將錯誤代碼與 Number 屬性 (Err 物件) 比對)。但是，請盡可能考慮以 Visual Basic 的結構化例外處理概觀 取代這類錯誤控制項。
備註
您可以使用 DateDiff 函式來決定兩個日期/時間值之間有多少個指定的時間間隔。例如，您可使用 DateDiff 來計算兩個日期之間的天數，或是從今天開始到年底的週數。
行為
**參數處理。**DateDiff 會以 Date2 值減掉 Date1 值來取得差值。這兩個值在呼叫程式中都不會變更。
**傳回值。**由於 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，因為這兩個日期間的差異少於七天，但是它將傳回 1 給 wY，因為這兩個行事曆週第一天之間的差異是七天。
.gif "注意事項")
警告：當 Date1 的時間部分大於 Date2 的時間部分，而且 Interval 設定為 DateInterval.WeekOfYear 時，則 DateDiff 函式傳回的值會比正確值小 1。
**較大間隔。**如果將 Interval 設定為 DateInterval.Year，則會單純地從 Date1 和 Date2 的年份部分計算傳回值。同樣地，會單純地從引數的年和月部分計算 DateInterval.Month 的傳回值；如果是 DateInterval.Quarter，則是從包含這兩個日期的季份計算。
例如，比較 12 月 31 日和來年的 1 月 1 日時，DateDiff 會針對 DateInterval.Year、DateInterval.Quarter 或 DateInterval.Month 傳回 1，即使最多只過了一天也一樣。
**其他間隔。**由於 DateTime 結構支援每個 Date 值，因此它的方法會在您尋找時間間隔時提供其他選項。例如，您可透過任一多載形式來使用 Subtract 方法：DateTime.Subtract 會從 Date 變數減去 TimeSpan，以傳回另一個 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)
需求
**模組︰**DateAndTime
組件：Visual Basic Runtime Library (在 Microsoft.VisualBasic.dll 中)