DateAndTime.DateDiff 方法

定義

命名空間:

Microsoft.VisualBasic

組件:

Microsoft.VisualBasic.Core.dll

傳回值，指定兩個 Date 值之間的時間間隔數目。

多載

DateDiff(DateInterval, DateTime, DateTime, FirstDayOfWeek, FirstWeekOfYear)	從 Date2 減去 Date1，以指定兩個 Date 值之間的時間間隔數目。
DateDiff(String, Object, Object, FirstDayOfWeek, FirstWeekOfYear)	從 Date2 減去 Date1，以指定兩個 Date 值之間的時間間隔數目。

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

來源:

DateAndTime.vb

從 Date2 減去 Date1，以指定兩個 Date 值之間的時間間隔數目。

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

參數

Interval

DateInterval

必填。 DateInterval 列舉值或字串表示式，表示您想要用來作為 Date1 與 Date2之間差異單位的時間間隔。

Date1

DateTime

必填。 您想要在計算中使用的第一個日期/時間值。

Date2

DateTime

必填。 您想要在計算中使用的第二個日期/時間值。

DayOfWeek

FirstDayOfWeek

自選。 從指定一周第一天之 FirstDayOfWeek 列舉中選擇的值。 如果未指定，則會使用 Sunday。

WeekOfYear

FirstWeekOfYear

自選。 從指定年份第一周之 FirstWeekOfYear 列舉中選擇的值。 如果未指定，則會使用 Jan1。

傳回

Int64

指定兩個 Date 值之間的時間間隔數目的長值。

例外狀況

ArgumentException

Date1、Date2或 DayofWeek 超出範圍。

InvalidCastException

Date1 或 Date2 的類型無效。

範例

此範例會使用 DateDiff 函式來顯示指定日期與今天之間的天數。

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

備註

您可以使用 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，因為兩個日期之間的差異小於 7 天，但會傳回 1 到 wY，因為個別行事歷周的第一天之間有七天的差異。

• 較大的間隔。 如果 Interval 設定為 DateInterval.Year，則傳回值只會從 Date1 和 Date2的年份部分計算。 同樣地，DateInterval.Month 的傳回值只會從自變數的年份和月份部分計算，以及包含兩個日期的季 DateInterval.Quarter。

  例如，當比較次年 12 月 31 日與次年 1 月 1 日時，DateDiff 即使最多只有一天，DateInterval.Year、DateInterval.Quarter或 DateInterval.Month仍會傳回 1。

  對於具有多個紀元的日文等文化特性，如果差異跨越兩個以上的紀元，DateDiff 方法不會傳回年份的差異。 相反地，您可以計算 Year 屬性所傳回的值差異，如下列範例所示：date2.Year - date1.Year。

• 其他間隔。 由於 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 Double = runLength.TotalMilliseconds
  

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 月 1 日發生的週 （預設值）
FirstWeekOfYear.FirstFourDays	2	新年至少有四天的周（符合 ISO 標準 8601 第 3.17 節）
FirstWeekOfYear.FirstFullWeek	3	新年的第一整周

另請參閱

• DateAdd
• DatePart
• Day(DateTime)
• Format(Object, String)
• Now
• Weekday(DateTime, FirstDayOfWeek)
• Year(DateTime)
• DateTime
• TimeSpan
• 數據類型摘要 （Visual Basic）

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

來源:

DateAndTime.vb

從 Date2 減去 Date1，以指定兩個 Date 值之間的時間間隔數目。

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

參數

Interval

String

必填。 DateInterval 列舉值或字串表示式，表示您想要用來作為 Date1 與 Date2之間差異單位的時間間隔。

Date1

Object

必填。 您想要在計算中使用的第一個日期/時間值。

Date2

Object

必填。 您想要在計算中使用的第二個日期/時間值。

DayOfWeek

FirstDayOfWeek

自選。 從指定一周第一天之 FirstDayOfWeek 列舉中選擇的值。 如果未指定，則會使用 Sunday。

WeekOfYear

FirstWeekOfYear

自選。 從指定年份第一周之 FirstWeekOfYear 列舉中選擇的值。 如果未指定，則會使用 Jan1。

傳回

Int64

指定兩個 Date 值之間的時間間隔數目的長值。

例外狀況

ArgumentException

Date1、Date2或 DayofWeek 超出範圍。

InvalidCastException

Date1 或 Date2 的類型無效。

範例

此範例會使用 DateDiff 函式來顯示指定日期與今天之間的天數。

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

備註

您可以使用 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，因為兩個日期之間的差異小於 7 天，但會傳回 1 到 wY，因為個別行事歷周的第一天之間有七天的差異。

• 較大的間隔。 如果 Interval 設定為 DateInterval.Year，則傳回值只會從 Date1 和 Date2的年份部分計算。 同樣地，DateInterval.Month 的傳回值只會從自變數的年份和月份部分計算，以及包含兩個日期的季 DateInterval.Quarter。

  例如，當比較次年 12 月 31 日與次年 1 月 1 日時，DateDiff 即使最多只有一天，DateInterval.Year、DateInterval.Quarter或 DateInterval.Month仍會傳回 1。

  對於具有多個紀元的日文等文化特性，如果差異跨越兩個以上的紀元，DateDiff 方法不會傳回年份的差異。 相反地，您可以計算 Year 屬性所傳回的值差異，如下列範例所示：date2.Year - date1.Year。

• 其他間隔。 由於 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 Double = runLength.TotalMilliseconds
  

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 月 1 日發生的週 （預設值）
FirstWeekOfYear.FirstFourDays	2	新年至少有四天的周（符合 ISO 標準 8601 第 3.17 節）
FirstWeekOfYear.FirstFullWeek	3	新年的第一整周

另請參閱

• DateAdd
• DatePart
• Day(DateTime)
• Format(Object, String)
• Now
• Weekday(DateTime, FirstDayOfWeek)
• Year(DateTime)
• DateTime
• TimeSpan
• 數據類型摘要 （Visual Basic）